<!DOCTYPE html>
<html lang="en">
<head>
	<meta charset="UTF-8">
	<meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
	<title>Split index API | ElasticSearch 7.7 权威指南中文版</title>
	<meta name="keywords" content="ElasticSearch 权威指南中文版, elasticsearch 7, es7, 实时数据分析，实时数据检索" />
    <meta name="description" content="ElasticSearch 权威指南中文版, elasticsearch 7, es7, 实时数据分析，实时数据检索" />
    <!-- Give IE8 a fighting chance -->
    <!--[if lt IE 9]>
    <script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
    <script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
    <![endif]-->
	<link rel="stylesheet" type="text/css" href="../static/styles.css" />
	<script>
	var _link = 'indices-split-index.html';
    </script>
</head>
<body>
<div class="main-container">
    <section id="content">
        <div class="content-wrapper">
            <section id="guide" lang="zh_cn">
                <div class="container">
                    <div class="row">
                        <div class="col-xs-12 col-sm-8 col-md-8 guide-section">
                            <div style="color:gray; word-break: break-all; font-size:12px;">原英文版地址: <a href="https://www.elastic.co/guide/en/elasticsearch/reference/7.7/indices-split-index.html" rel="nofollow" target="_blank">https://www.elastic.co/guide/en/elasticsearch/reference/7.7/indices-split-index.html</a>, 原文档版权归 www.elastic.co 所有<br/>本地英文版地址: <a href="../en/indices-split-index.html" rel="nofollow" target="_blank">../en/indices-split-index.html</a></div>
                        <!-- start body -->
                  <div class="page_header">
<strong>重要</strong>: 此版本不会发布额外的bug修复或文档更新。最新信息请参考 <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/index.html" rel="nofollow">当前版本文档</a>。
</div>
<div id="content">
<div class="breadcrumbs">
<span class="breadcrumb-link"><a href="index.html">Elasticsearch Guide [7.7]</a></span>
»
<span class="breadcrumb-link"><a href="rest-apis.html">REST APIs</a></span>
»
<span class="breadcrumb-link"><a href="indices.html">Index APIs</a></span>
»
<span class="breadcrumb-node">Split index API</span>
</div>
<div class="navheader">
<span class="prev">
<a href="indices-shrink-index.html">« Shrink index API</a>
</span>
<span class="next">
<a href="indices-synced-flush-api.html">Synced flush API »</a>
</span>
</div>
<div class="section">
<div class="titlepage"><div><div>
<h2 class="title">
<a id="indices-split-index"></a>Split index API<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/indices/split-index.asciidoc">edit</a>
</h2>
</div></div></div>

<p>Splits an existing index into a new index with more primary shards.</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST /twitter/_split/split-twitter-index
{
  "settings": {
    "index.number_of_shards": 2
  }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/1727.console"></div>
<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="split-index-api-request"></a>Request<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/indices/split-index.asciidoc">edit</a>
</h3>
</div></div></div>
<p><code class="literal">POST /&lt;index&gt;/_split/&lt;target-index&gt;</code></p>
<p><code class="literal">PUT /&lt;index&gt;/_split/&lt;target-index&gt;</code></p>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="split-index-api-prereqs"></a>Prerequisites<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/indices/split-index.asciidoc">edit</a>
</h3>
</div></div></div>
<p>Before you can split an index:</p>
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
The index must be read-only.
</li>
<li class="listitem">
The <a class="xref" href="cluster-health.html" title="Cluster health API">cluster health</a> status must be green.
</li>
</ul>
</div>
<p>You can do make an index read-only
with the following request:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">PUT /my_source_index/_settings
{
  "settings": {
    "index.blocks.write": true <a id="CO579-1"></a><i class="conum" data-value="1"></i>
  }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/1728.console"></div>
<div class="calloutlist">
<table border="0" summary="Callout list">
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO579-1"><i class="conum" data-value="1"></i></a></p>
</td>
<td align="left" valign="top">
<p>Prevents write operations to this index while still allowing metadata
changes like deleting the index.</p>
</td>
</tr>
</table>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="split-index-api-desc"></a>Description<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/indices/split-index.asciidoc">edit</a>
</h3>
</div></div></div>
<p>The split index API allows you to split an existing index into a new index,
where each original primary shard is split into two or more primary shards in
the new index.</p>
<p>The number of times the index can be split (and the number of shards that each
original shard can be split into) is determined by the
<code class="literal">index.number_of_routing_shards</code> setting. The number of routing shards
specifies the hashing space that is used internally to distribute documents
across shards with consistent hashing. For instance, a 5 shard index with
<code class="literal">number_of_routing_shards</code> set to <code class="literal">30</code> (<code class="literal">5 x 2 x 3</code>) could be split by a
factor of <code class="literal">2</code> or <code class="literal">3</code>.  In other words, it could be split as follows:</p>
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
<code class="literal">5</code> → <code class="literal">10</code> → <code class="literal">30</code>  (split by 2, then by 3)
</li>
<li class="listitem">
<code class="literal">5</code> → <code class="literal">15</code> → <code class="literal">30</code> (split by 3, then by 2)
</li>
<li class="listitem">
<code class="literal">5</code> → <code class="literal">30</code> (split by 6)
</li>
</ul>
</div>
<p>While you can set the <code class="literal">index.number_of_routing_shards</code> setting explicitly at
index creation time, the default value depends upon the number of primary
shards in the original index.  The default is designed to allow you to split
by factors of 2 up to a maximum of 1024 shards.  However, the original number
of primary shards must taken into account.  For instance, an index created
with 5 primary shards could be split into 10, 20, 40, 80, 160, 320, or a
maximum of 640 shards (with a single split action or multiple split actions).</p>
<p>If the original index contains one primary shard (or a multi-shard index has
been <a class="xref" href="indices-shrink-index.html" title="Shrink index API">shrunk</a> down to a single primary shard), then the
index may by split into an arbitrary number of shards greater than 1.  The
properties of the default number of routing shards will then apply to the
newly split index.</p>
<div class="section">
<div class="titlepage"><div><div>
<h4 class="title">
<a id="how-split-works"></a>How splitting works<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/indices/split-index.asciidoc">edit</a>
</h4>
</div></div></div>
<p>A split operation:</p>
<div class="olist orderedlist">
<ol class="orderedlist">
<li class="listitem">
Creates a new target index with the same definition as the source
index, but with a larger number of primary shards.
</li>
<li class="listitem">
Hard-links segments from the source index into the target index. (If
the file system doesn’t support hard-linking, then all segments are copied
into the new index, which is a much more time consuming process.)
</li>
<li class="listitem">
Hashes all documents again, after low level files are created, to delete
documents that belong to a different shard.
</li>
<li class="listitem">
Recovers the target index as though it were a closed index which
had just been re-opened.
</li>
</ol>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h4 class="title">
<a id="incremental-resharding"></a>Why doesn’t Elasticsearch support incremental resharding?<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/indices/split-index.asciidoc">edit</a>
</h4>
</div></div></div>
<p>Going from <code class="literal">N</code> shards to <code class="literal">N+1</code> shards, aka. incremental resharding, is indeed a
feature that is supported by many key-value stores. Adding a new shard and
pushing new data to this new shard only is not an option: this would likely be
an indexing bottleneck, and figuring out which shard a document belongs to
given its <code class="literal">_id</code>, which is necessary for get, delete and update requests, would
become quite complex. This means that we need to rebalance existing data using
a different hashing scheme.</p>
<p>The most common way that key-value stores do this efficiently is by using
consistent hashing. Consistent hashing only requires <code class="literal">1/N</code>-th of the keys to
be relocated when growing the number of shards from <code class="literal">N</code> to <code class="literal">N+1</code>. However
Elasticsearch’s unit of storage, shards, are Lucene indices. Because of their
search-oriented data structure, taking a significant portion of a Lucene index,
be it only 5% of documents, deleting them and indexing them on another shard
typically comes with a much higher cost than with a key-value store. This cost
is kept reasonable when growing the number of shards by a multiplicative factor
as described in the above section: this allows Elasticsearch to perform the
split locally, which in-turn allows to perform the split at the index level
rather than reindexing documents that need to move, as well as using hard links
for efficient file copying.</p>
<p>In the case of append-only data, it is possible to get more flexibility by
creating a new index and pushing new data to it, while adding an alias that
covers both the old and the new index for read operations. Assuming that the
old and new indices have respectively <code class="literal">M</code> and <code class="literal">N</code> shards, this has no overhead
compared to searching an index that would have <code class="literal">M+N</code> shards.</p>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h4 class="title">
<a id="split-index"></a>Split an index<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/indices/split-index.asciidoc">edit</a>
</h4>
</div></div></div>
<p>To split <code class="literal">my_source_index</code> into a new index called <code class="literal">my_target_index</code>, issue
the following request:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST /my_source_index/_split/my_target_index
{
  "settings": {
    "index.number_of_shards": 2
  }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/1729.console"></div>
<p>The above request returns immediately once the target index has been added to
the cluster state — it doesn’t wait for the split operation to start.</p>
<div class="important admon">
<div class="icon"></div>
<div class="admon_content">
<p>Indices can only be split if they satisfy the following requirements:</p>
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
the target index must not exist
</li>
<li class="listitem">
The source index must have fewer primary shards than the target index.
</li>
<li class="listitem">
The number of primary shards in the target index must be a multiple of the
number of primary shards in the source index.
</li>
<li class="listitem">
The node handling the split process must have sufficient free disk space to
accommodate a second copy of the existing index.
</li>
</ul>
</div>
</div>
</div>
<p>The <code class="literal">_split</code> API is similar to the <a class="xref" href="indices-create-index.html" title="Create index API"><code class="literal">create index</code> API</a>
and accepts <code class="literal">settings</code> and <code class="literal">aliases</code> parameters for the target index:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST /my_source_index/_split/my_target_index
{
  "settings": {
    "index.number_of_shards": 5 <a id="CO580-1"></a><i class="conum" data-value="1"></i>
  },
  "aliases": {
    "my_search_indices": {}
  }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/1730.console"></div>
<div class="calloutlist">
<table border="0" summary="Callout list">
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO580-1"><i class="conum" data-value="1"></i></a></p>
</td>
<td align="left" valign="top">
<p>The number of shards in the target index. This must be a multiple of the
number of shards in the source index.</p>
</td>
</tr>
</table>
</div>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p>Mappings may not be specified in the <code class="literal">_split</code> request.</p>
</div>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h4 class="title">
<a id="monitor-split"></a>Monitor the split process<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/indices/split-index.asciidoc">edit</a>
</h4>
</div></div></div>
<p>The split process can be monitored with the <a class="xref" href="cat-recovery.html" title="cat recovery API"><code class="literal">_cat recovery</code>
API</a>, or the <a class="xref" href="cluster-health.html" title="Cluster health API"><code class="literal">cluster health</code> API</a> can be used to wait
until all primary shards have been allocated by setting the  <code class="literal">wait_for_status</code>
parameter to <code class="literal">yellow</code>.</p>
<p>The <code class="literal">_split</code> API returns as soon as the target index has been added to the
cluster state, before any shards have been allocated. At this point, all
shards are in the state <code class="literal">unassigned</code>. If, for any reason, the target index
can’t be allocated, its primary shard will remain <code class="literal">unassigned</code> until it
can be allocated on that node.</p>
<p>Once the primary shard is allocated, it moves to state <code class="literal">initializing</code>, and the
split process begins. When the split operation completes, the shard will
become <code class="literal">active</code>. At that  point, Elasticsearch will try to allocate any
replicas and may decide to relocate the primary shard to another node.</p>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h4 class="title">
<a id="split-wait-active-shards"></a>Wait for active shards<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/indices/split-index.asciidoc">edit</a>
</h4>
</div></div></div>
<p>Because the split operation creates a new index to split the shards to,
the <a class="xref" href="indices-create-index.html#create-index-wait-for-active-shards" title="Wait For active shards">wait for active shards</a> setting
on index creation applies to the split index action as well.</p>
</div>

</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="split-index-api-path-params"></a>Path parameters<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/indices/split-index.asciidoc">edit</a>
</h3>
</div></div></div>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">&lt;index&gt;</code>
</span>
</dt>
<dd>
(Required, string)
Name of the source index to split.
</dd>
<dt>
<span class="term">
<code class="literal">&lt;target-index&gt;</code>
</span>
</dt>
<dd>
<p>(Required, string)
Name of the target index to create.</p>
<p>Index names must meet the following criteria:</p>
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
Lowercase only
</li>
<li class="listitem">
Cannot include <code class="literal">\</code>, <code class="literal">/</code>, <code class="literal">*</code>, <code class="literal">?</code>, <code class="literal">"</code>, <code class="literal">&lt;</code>, <code class="literal">&gt;</code>, <code class="literal">|</code>, ` ` (space character), <code class="literal">,</code>, <code class="literal">#</code>
</li>
<li class="listitem">
Indices prior to 7.0 could contain a colon (<code class="literal">:</code>), but that’s been deprecated and won’t be supported in 7.0+
</li>
<li class="listitem">
Cannot start with <code class="literal">-</code>, <code class="literal">_</code>, <code class="literal">+</code>
</li>
<li class="listitem">
Cannot be <code class="literal">.</code> or <code class="literal">..</code>
</li>
<li class="listitem">
Cannot be longer than 255 bytes (note it is bytes, so multi-byte characters will count towards the 255 limit faster)
</li>
<li class="listitem">
Names starting with <code class="literal">.</code> are deprecated, except for <a class="xref" href="index-modules.html#index-hidden">hidden indices</a> and internal indices managed by plugins
</li>
</ul>
</div>
</dd>
</dl>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="split-index-api-query-params"></a>Query parameters<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/indices/split-index.asciidoc">edit</a>
</h3>
</div></div></div>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">wait_for_active_shards</code>
</span>
</dt>
<dd>
<p>(Optional, string) The number of shard copies that must be active before
proceeding with the operation. Set to <code class="literal">all</code> or any positive integer up
to the total number of shards in the index (<code class="literal">number_of_replicas+1</code>).
Default: 1, the primary shard.</p>
<p>See <a class="xref" href="docs-index_.html#index-wait-for-active-shards" title="Active shards">Active shards</a>.</p>
</dd>
<dt>
<span class="term">
<code class="literal">master_timeout</code>
</span>
</dt>
<dd>
(Optional, <a class="xref" href="common-options.html#time-units" title="Time units">time units</a>) Specifies the period of time to wait for
a connection to the master node. If no response is received before the timeout
expires, the request fails and returns an error. Defaults to <code class="literal">30s</code>.
</dd>
<dt>
<span class="term">
<code class="literal">timeout</code>
</span>
</dt>
<dd>
(Optional, <a class="xref" href="common-options.html#time-units" title="Time units">time units</a>) Specifies the period of time to wait for
a response. If no response is received before the timeout expires, the request
fails and returns an error. Defaults to <code class="literal">30s</code>.
</dd>
</dl>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="split-index-api-request-body"></a>Request body<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/indices/split-index.asciidoc">edit</a>
</h3>
</div></div></div>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">aliases</code>
</span>
</dt>
<dd>
(Optional, <a class="xref" href="indices-aliases.html" title="Update index alias API">alias object</a>)
Index aliases which include the target index.
See <a class="xref" href="indices-aliases.html" title="Update index alias API">Update index alias</a>.
</dd>
<dt>
<span class="term">
<code class="literal">settings</code>
</span>
</dt>
<dd>
(Optional, <a class="xref" href="index-modules.html#index-modules-settings" title="Index Settings">index setting object</a>)
Configuration options for the target index.
See <a class="xref" href="index-modules.html#index-modules-settings" title="Index Settings">Index Settings</a>.
</dd>
</dl>
</div>
</div>

</div>
<div class="navfooter">
<span class="prev">
<a href="indices-shrink-index.html">« Shrink index API</a>
</span>
<span class="next">
<a href="indices-synced-flush-api.html">Synced flush API »</a>
</span>
</div>
</div>

                  <!-- end body -->
                        </div>
                        <div class="col-xs-12 col-sm-4 col-md-4" id="right_col">
                        
                        </div>
                    </div>
                </div>
            </section>
        </div>
    </section>
</div>
<script src="../static/cn.js"></script>
</body>
</html>